AE REST API - General Info

As a developer or system administrator, you can use the REST API to communicate with the Automation Engine system using a technology-independent state-of-the-art interface.

This page includes the following:

Overview

The AE REST API provides an interface for third-party applications to interact with the Automation Engine. The AE REST API also allows the user to target the Automation Engine not only from Java, but from many programming languages.

The REST requests and responses contain JSON structured data:

Optional properties with value null might be omitted in the response payload.

The AE REST API supports both HTTP and HTTPS (recommended). HTTPS can be set with the parameter sslEnabled in the Automation Engine configuration file (ucsrv.ini).

More Information:

The current version of the AE REST API is v1. This information is reflected in the URI and is therefore relevant when accessing your AE REST API interface.

The AE REST API can be installed multiple times. The installation can be either with different port numbers on one node or on different nodes with the same port number.

Notes:

All timestamp values are returned as saved in the database and are not converted by the Automation Engine. The REST client is in charge of any conversion.
The Automation Engine does not check if a time zone object exists when executing an object. The AE REST API does not check it either.
When you use AE authentication and you import a User object, the User is locked. It must be unlocked in Client 0 and a new password must be set. This behavior does not apply when using LDAP authentication. For more information, see About LDAP.

AE REST API and ILM

During the daily operation of an Automation Engine system, large amounts of reporting, statistical, and historical data accumulate. Partitioning the database with ILM is an efficient method to deal with it and maintain the object version and the deleted object data. ILM actions require switching out parts of the Automation Engine database tables; therefore, no database actions should take place while working with ILM. For more information, see ILM - Information Lifecycle Management.

Important! The AE REST web service automatically detects if there are any ongoing ILM actions and, if so, it blocks specific REST requests. In this case, an error message is returned, indicating that the REST API is momentarily not available due to ILM actions.

Localization

REST API messages are by default in English. The AE REST API does not support any other language.

Setting up Multiple REST API Processes

The JCP installation is relevant for the AE REST API and for the advanced object search. You can install a single JCP. In this case, all REST requests are sent to this single AE REST API instance and no REST API is available if the JCP is down. For more information, see Installing the JCP.

You can also set up a system with multiple JCPs. In this case, two JCPs are used in a cluster but only one of both is available at the time.

Important! When using multiple JCPs, it is imperative that each JCP uses its own Automation Engine configuration file (ucsrv.ini). For more information, see Automation Engine. If only one INI file is used for more than one JCP, the first one connects successfully while the others terminated upon trying to register the same REST port if both run on the same node. An error message is written to the log file of the JCP stating the reason for termination.

Setting up a system with multiple JCPs can be convenient for balancing and to provide failover capabilities, because the REST requests are sent and distributed only to available JCPs.

To use this configuration, a JCP must be installed on each node. Port1 and port2 can have the same port number (for example, 8088, the default value in the configuration file) because the JCPs/REST web services are running on different hosts (host1 and host2). Host3:port3 must be public available as single point of contact for all AE REST API requests. Host1:port1 and host2:port2 must be known only by the HTTP/HTTPS proxy.

If a virtual IP is being used, both JCPs can be reached through the same IP address, which means that the endpoints have the same base URI: http(s)://{host}:{port}/ae/api/v1/{client}/....

The REST client or a HTTP/HTTPS proxy periodically sends a /ping request to check the JCPs availability. Depending on the result, the HTTP/HTTPS proxy knows which JCPs are available at the moment.

In a High Availability active/active setting, both are intended to be available.
In a High Availability active/passive setting, only one of them is intended to be available.

The REST client or HTTP/HTTPS then decides where to send the REST requests, depending on the selection strategy of the proxy. When the REST client sends requests to the HTTP/HTTPS proxy (host3:port3), the proxy dispatches them automatically to a JCP/REST web service.

In a High Availability active/active setting, it sends it to one of both available. Which one is used depends on the selecting strategy of the proxy (for example, lowest load or connections).
In a High Availability active/passive setting, it sends it to the one that is available.

Health Check Requests

The AE REST API provides two different health checks:

a fast /ping request to be used by HTTP/HTTPS proxies to ensure that the JCP and REST web service is available. This health check does not provide any details on the required backend components:

../ping
a system information health check which provides details on the JCP and REST web service. This health check also provides details on the required backend components:

../{client}/system/health

Authentication

The AE REST API supports Basic Authentication. The user, department, and password information are part of the HTTP(S) header and therefore used for Basic Authentication. The Automation Engine decides whether a REST request in the user context is allowed or not and responses accordingly.

The AE REST API does not support password encryption for the password that is stated in the REST request. It is recommended to use HTTPS to secure the transmission of this information. For more information, see Encoding Passwords.

Authorizations

An efficient and secure system to protect the access to data is a key part of our security concept. Security at data level can be as broad as administrator access to a role, or as granular as Read access to only one job in one specific folder. For more information, see Access Control.

The AE REST API also requires certain authorizations to perform different operations and checks if they are in place when performing them.

To retrieve variables, comments, and reports of an execution (GET) you need the authorization S - Executions.
To add comments to an execution (POST), you need the authorization M - Modify at runtime.

For more information, see Granting Automation Engine Authorizations.

Generate at Runtime

To avoid request timeouts, the objects to be executed must have the attribute Generate Task at Runtime set. When executing and object, the system checks if this attribute has been set accordingly. If it has not been set, the execution is not started.

More Information:

By setting this attribute the RunID is returned immediately, so that the REST response follows the request straightaway.

If this attribute is set to Generate Task at Activation Time, long processing might prevent immediate REST response which may result in a timeout.

Note: When restarting an execution, the attribute Generate Task at Runtime is not set.

AEREST API Polling

You can poll the server to check the status of a REST request/response sequence in case the desired result is not yet available. For example, you could poll the server after executing an object and getting the RunID to check if the execution has ended.

The following sample shows how polling for execution status can be done through the AE REST API:

Input through PromptSet

PromptSet variables can be passed through the AE REST API request on execution given the objects to be executed have at least one PromptSet assigned.

Example of REST request content:

PromptSet variable	Field type	Recommendations
"&TEXT1#"	Text field	n/a
"&NUMBER1#"	Number field	n/a
"&CHECKBOX_ARRAY#"	Checkbox field*	Array=true
&CHECKBOX_STRING#	Checkbox field	Array = false, separator = ";"
"&MULTILINE1#"	Multi-line text field	Attribute "Multi-line" checked, \n for line breaks

* It is recommended to define a Checkbox field as Array when used to pass values through the AE REST API.

Notes:

The attribute "Array" of the PromptSet field CHECKBOX_ARRAY has to be set to true because the Automation Engine must handle it as an array.
No object variables can be set here.
Some REST requests contain the parameter inputs, which lists PromptSet variables. This context implies that they are all variables and there is no need to state explicitly a leading "&". The trailing "#" depends on the variable definition. For more information, see Variables and VARA Objects.

Filter for Execution List

The request GET ../v1/{client}/executions returns a list of all executions. You can add query parameters as part of the URI to filter the them.

Note: The Automic Web Interface has different settings for list views that are relevant when applying filters. The hierarchical view, which, when using filters, affects only parent tasks and the list view, which affects both, parent and child tasks. The AE REST API supports only the list view.

You can apply filters for the following execution parameters:

name

Enter the name (..?name=[NAME]) or part of the name (..?name=[NAM]*) of the execution you are searching for.

Note: You can only use the query parameter once.
alias

The alias is an optional, additional name that is given to a task when it is part of a workflow. If defined, the alias is displayed instead of its name.

Enter the alias (..?alias=[NAME]) or part of the alias (..?alias=[NAM]*) of the execution you are searching for.

Note: You can only use the query parameter once.

In case you want to set special characters for the execution alias, you must define the parameter ALIAS_SPECIAL_CHARACTERS in UC_CLIENT_SETTINGS - Various Client Settings in the relevant Client.
type

You can add query parameters to filter for the following objects: CALL, SCRI, JOBD, CPIT, JOBG, C_PERIOD, JOBF, REPORT (agent job reports only), JSCH, JOBP, JOBS, JOBQ, EVNT, API, C_HOSTG. For more information, see Objects.

Note: This parameter allows you to use multiple values. You can either use the parameter once and separate the values with comas (type=JOBS,JOBP) or use the parameter more than once in a request (type=JOBS&type=JOBP).
Time frame

Use a combination of the following parameters to find executions within a given time frame.
- time_frame_option: Use this parameter to define which kind of executions you want to find within a certain timeframe. The values that are allowed are:
  - all: all executions that start, end, or run within the specified timeframe
  - activation: all executions that are activated within the specified time frame
  - start: all executions that started within the specified time frame
  - end: all executions that ended within the specified time frame
- time_frame_from: starting date and time frame
- time_frame_to: final date and time frame
status

Use this parameter to search for any possible status that is recorded by the Automation Engine. For more information, see System Return Codes of Executable Objects.

Note: This parameter allows you to use multiple values. You can either use the parameter once and separate the values with comas (status=1900,1800) or use the parameter more than once in a request (status=1900&status=1800).
agent

Enter the agent name (..?agent=[NAME]) or part of the agent name (..?agent=[NAM]*) of the execution you are searching for.

Note: You can only use the query parameter once.
platform

Use this parameter to find executions that have been processed by a specific agent type, for example, all executions processed by Windows Agents.

Note: This parameter allows you to use multiple values. You can either use the parameter once and separate the values with comas (platform=WIN,LINUX) or use the parameter more than once in a request (platform=WIN&platform=LINUX).
queue

Use this parameter to search for execution queues.

Note: This parameter allows you to use multiple values. You can either use the parameter once and separate the values with comas (queue=CLIENT_QUEUE,PRIO_QUEUE) or use the parameter more than once in a request (queue=CLIENT_QUEUE&queue=PRIO_QUEUE).
include_deactivated

Use include_deactivated to include deactivated executions in the search when applying filters, because they are not considered by default.

This parameter can have an impact on the time frame:
- If the parameter is =false or missing and no time frame is defined, the internal default for the time frame is unlimited
- If the parameter is =true and no time frame is defined, the internal default for the time frame is 12 hours.

You can combine the query parameters as required to build simple or complex filters. For example, you can:

Search for a specific execution name excluding deactivated executions

../executions?name=JOBS.24
Search for a specific execution name including deactivated executions

../executions?name=JOBS.24&include_deactivated=true
Search for a specific set of execution types

../executions?type=JOBP&type=JOBS

../executions?type=JOBP,JOBS
Search for an absolute time frame

../executions?time_frame_option=all&time_frame_from=2017-07-04T12:43:45Z&time_frame_to=2017-07-04T06:23:12Z
Use wildcards (supported for name, alias, agent, user, and archive_key1&2)

Note: If you use the wildcard * in your search, you can only use the respective query parameter once.

../executions?name=NAME

../executions?alias=NAM*
Use complex filters

../executions?name=OBJECT&type=JOBP&type=JOBS&queue=CLIENT_QUEUE&queue=PRIO_QUEUE&status=1900,1800&include_deactivated=true&time_frame_option=all&time_frame_from=2017-07-04T12:43:45Z&time_frame_to=2017-07-04T06:23:12Z

Pagination for Child Task Executions and Execution Lists

Pagination can be useful if a request to the AE REST API returns numerous results, because the result set, which can change fast and often, is divided into chunks (pages) per request/response. For example, if you send a request to get all the child task executions of a specific execution, thousands of records may be retrieved. In AE REST API, you can use pagination to make results easy to handle.

Limit Parameters

AE REST API allows you to set the following limit parameters:

max_results

Defines the maximum number of results per page.

Default value: 50

If this parameter is omitted, the default value is used.
start_at_run_id

Defines the RunID of the last entry of the previous page.

If this parameter is omitted, the first page is returned.

URI Structure with Pagination Parameters

The URI including the pagination parameters consists of the following elements:

http://{host}:{port}/ae/api/v1/{client}/executions/{runid}/children?max_results={number}&start_at_run_id={runid}

For example:

http://192.168.40.116:8088/ae/api/v1/100/executions/1003003/children?max_results=10&start_at_run_id=100301

In this example, the requested parent execution 1003003 has 25 child task executions requested. The paginated response is distributed as follows:

Page	Request URI	Response Payload	Comment
1	../executions/1003003/children?max_results=10	List of the first 10 executions RunID of last execution listed =1003045 "hasmore"=true() "total"=25(*)	If the parameter start_at_run_id is omitted, the first page is returned.
2	../executions/1003003/children?max_results=10&start_at_run_id=1003045	List of the next 10 executions RunID of first execution listed <1003045 RunID of last execution listed =1003034 "hasmore"=true() "total"=25(*)	The RunID of the first execution on page 2 is lower than the RunID of the last execution on page 1, thus avoiding duplicate listings.
3	../executions/1003003/children?max_results=10&start_at_run_id=1003034	List of the next 5 executions RunID of first execution listed <1003034 RunID of last execution listed =1003028 "hasmore"=false() "total"=25(*)	"hasmore"=false indicates that this is the last page.

Page

Request URI

Response Payload

Comment

../executions/1003003/children?max_results=10

List of the first 10 executions

RunID of last execution listed =1003045

"hasmore"=true(*)

"total"=25(**)

If the parameter start_at_run_id is omitted, the first page is returned.

../executions/1003003/children?max_results=10&start_at_run_id=1003045

List of the next 10 executions

RunID of first execution listed <1003045

RunID of last execution listed =1003034

"hasmore"=true(*)

"total"=25(**)

The RunID of the first execution on page 2 is lower than the RunID of the last execution on page 1, thus avoiding duplicate listings.

../executions/1003003/children?max_results=10&start_at_run_id=1003034

List of the next 5 executions

RunID of first execution listed <1003034

RunID of last execution listed =1003028

"hasmore"=false(*)

"total"=25(**)

"hasmore"=false indicates that this is the last page.

* total: indicates the total number of resources in the collection and helps determine how many pages the result would have.
**hasmore: has the following possible values:
- true = more pages are available
- false = you have reached the last page

Notes:

The executions that are displayed on a given page are ordered by activation time and RunID descending.
Pagination might provide an incomplete list of child task executions. For example, if a requested page P lists all executions with activation time >=T1 and RunID < R1 and a new execution E is generated at a later point with the same activation time but with RunID < R1, the execution E is not listed neither on page P nor in any following page.

Pagination for Reports

Pagination is also useful when a report is rather large and its content is split into report pages. The AE REST API paginates these report pages.

Limit Parameters

max_results

Defines the maximum number of entries (report pages) returned.

Default value: 1

If this parameter is set to zero (0), no entries are returned.
start_at

Defines the number of the start page (entry/report page) returned.

Default value: 1

If this parameter is not defined, the entries returned start with the first report page. If the value defined is larger than the number of entries available, no information is returned, because the request exceeds the range of report pages available.

For example:
- ...exectutions/{run id}/reports/REP returns the whole report (all report pages)
- ...exectutions/{run id}/reports/REP?max_results=3 returns the first chunk of three (3) report pages (report pages 1, 2, and 3)
- ...exectutions/{run id}/reports/REP?max_results=3&start_at=4 returns the second chunk of three (3) (report pages 4, 5, and 6)
- ...exectutions/{run id}/reports/REP?start_at=2 returns all report pages except the first one

Important! The AE REST API can only request the content of reports available in the AE database. A job report is stored in the database only if the Store to: Database option has been selected in the Job Report section of the job definition page. This option is selected by default.

Tracing

All REST activities can be traced for analysis purposes. To do so select a JCP and right-click to select Advanced Options. This action opens a dialog where you can specify trace flags.

The trace flag can also be set in the Automation Engine configuration (INI) file. To do so, set the JCL key in the TRACE section of the INI file. The relevant values for the RA Web Service REST Agent are:

0: Tracing disabled
1: Traces REST headers and content
2: Traces also login information

Web Server Configuration

The Automation Engine REST web service uses a web server which largely uses a predefined configuration. As a system administrator, you can customize the parameters that are listed here in [REST] section of the configuration file (ucsrv.ini):

Cross-Origin Resource Sharing / Same Origin Policy (CORS/SOP)
- corsSupportEnabled
- corsAccessControlAllowOrigin
GZIP Compression
- gzipSupportEnable
ThreadPool
- minPoolSize
- maxPoolSize
- idleTimeout

For more information, see Automation Engine.

CORS/SOP

The Same Origin Policy (SOP) prevents web clients from carrying out cross-origin requests. You can circumvent this policy using Cross-Origin Resource Sharing (CORS) to allow origins explicitly.

For example:

Host 3 requests a web document from origin 1 (Host 1, web server) at http://host1:80 (default http port). Host 3 then requests information from origin 2 (Host 2, AE) at http://host2:8080 (default AE REST web service port). The most common web browsers check whether cross domain requests are allowed or not. If not, the request to the second origin http://host2:8080 is not allowed.

To allow such cross origin requests, the AE REST web service must explicitly tell the web browser to allow the request. You can define it using the following CORS parameters in the [REST] section of the Automation Engine configuration file (ucsrv.ini):

corsSupportEnabled=1
corsAccessControlAllowOrigin=http://host1:80

For more information, see Automation Engine.

If the web server runs on the same local host as the browser or web client (Host1 = Host3), you must implement a simple web-based REST client by setting the parameter corsAccessControlAllowOrigin to http://localhost:80.

Compression

A REST client can state in a request that the response payload should be compressed to improve performance. If the REST web service supports compression, it sends back the payload in gzip format.

Compression support is disabled by default. You can enable it using the parameter gzipSupportEnabled in the [REST] section of the Automation Engine configuration file (ucsrv.ini). For more information, see Automation Engine.

Thread Pooling

The web server that is used by the JCP/REST web service processes requests with help of threads. The more threads are used, the more REST requests can be processed in parallel.

A thread pool keeps multiple threads waiting to process REST requests. The more requests come in, the more threads the web server automatically makes available within the range that is defined in minPoolSize >= N <= maxPoolSize. If some of the N threads remain unused for a period longer than the timeout period defined in the parameter idleTimeout, these are killed to free resources on the JCP process.